package lz.controls.managers
{
	import flash.display.InteractiveObject;
	import flash.display.Sprite;
	
	import lz.controls.Button;

	/**
	 * 实现 IFocusManager 接口以创建自定义焦点管理器。 
	 * 焦点管理器使应用程序能够在用户移动鼠标或按 Tab 键时将焦点在组件之间进行转移。
	 */
	public interface IFocusManager
	{
		/**
		 * 获取或设置对默认按钮的引用。 
		 * 当按下 Enter 键时，默认按钮用作具有焦点的任何组件的代理按钮。 
		 * 按 Enter 键将触发对代表具有焦点的组件的默认按钮调度 click 事件。 
		 * Button 组件不需要默认按钮。 
		 * 当焦点移动到 Button 组件时，不能触发默认按钮；
		 * 如果焦点从一个 Button 组件移动到一个不是按钮的组件，可能会再次触发默认按钮。
		 */
		function get defaultButton():Button;
		function set defaultButton(value:Button):void;
		//----------------------------------
		//  defaultButtonEnabled
		//----------------------------------
		/**
		 * 获取或设置一个值，该值指示是否启用默认按钮。
		 * 如果此值设置为 true，则焦点管理器会监视 Enter 键，并且如果在不是 Button 组件的组件具有焦点时按下 Enter 键，即会调度默认按钮的 click 事件。
		 * 如果此值设置为 false，则焦点管理器不监视 Enter 键。使用 Enter 键的组件将此属性设置为 false，以防止有默认按钮并且用户按 Enter 键的情况下，在默认按钮上调度 click 事件。
		 */
		function get defaultButtonEnabled():Boolean;
		function set defaultButtonEnabled(value:Boolean):void;
		//----------------------------------
		//  nextTabIndex
		//----------------------------------
		/**
		 * 获取要在当前 Tab 键循环中使用的下一个唯一 Tab 键索引。 
		 * Tab 键循环包含一个或多个由焦点管理器管理的组件。
		 */
		function get nextTabIndex():int;
		//----------------------------------
		//  showFocusIndicator
		//----------------------------------
		/**
		 * 获取或设置一个值，确定用户界面是否更改以指示特定的组件具有焦点。
		 * 如果此属性设置为 true，具有焦点的组件将用可视指示符标记。
		 * 如果设置为 false，则不会使用可视焦点指示符。
		 * 默认情况下，在用户按 Tab 键之前该属性设置为 false，之后则设置为 true。.
		 */
		function get showFocusIndicator():Boolean;
		function set showFocusIndicator(value:Boolean):void;
		//==========================================================================
		//  Methods
		//==========================================================================
		/**
		 * 检索当前具有焦点的 IFocusManagerComponent 组件。 
		 * 使用此方法来确定哪个组件具有焦点。 
		 * 使用 Stage 对象来确定哪个组件具有焦点可能会导致返回具有焦点的组件的子组件。
		 * 返回
		 * InteractiveObject — 具有焦点的 IFocusManagerComponent 对象。
		 */
		function getFocus():InteractiveObject;
		/**
		 * 将焦点设置到 IFocusManagerComponent 组件。此方法不检查组件的可见性、启用状态或任何其它条件。
		 * 参数
		 * o:InteractiveObject — 将获得焦点的组件。
		 */
		function setFocus(o:InteractiveObject):void;
		/**
		 * 将 showFocusIndicator 属性设置为 true。
		 * 如果组件具有焦点，此方法会在该组件上绘制可视焦点指示符。
		 */
		function showFocus():void;
		/**
		 * 将 showFocusIndicator 属性设置为 false。
		 * 如果具有焦点的组件标有可视焦点指示符，此方法将删除该指示符。
		 */
		function hideFocus():void;
		/**
		 * 激活焦点管理器。
		 * 如果屏幕上同时显示多个 DisplayObjectContainer 对象，则随着焦点从一个容器移动到下一个容器，系统管理器将激活和取消激活其 FocusManager 对象。 
		 * 如果焦点移动到其焦点管理器已取消激活的 DisplayObjectContainer 对象中的组件，系统管理器将通过调用 activate() 方法来激活该焦点管理器。 
		 * 一次只能有一个焦点管理器处于活动状态；在激活焦点管理器之前，系统管理器使用 deactivate() 方法取消激活其组件已失去焦点的活动焦点管理器。
		 */
		function activate():void;
		/**
		 * 取消激活焦点管理器。
		 * 如果屏幕上同时显示多个 DisplayObjectContainer 对象，则随着焦点从一个容器移动到下一个容器，系统管理器将激活和取消激活其 FocusManager 对象。 
		 * 如果焦点移动到其焦点管理器已取消激活的 DisplayObjectContainer 对象中的组件，系统管理器将通过调用 activate() 方法来激活该焦点管理器。 
		 * 一次只能有一个焦点管理器处于活动状态；在激活焦点管理器之前，系统管理器使用 deactivate() 方法取消激活其组件已失去焦点的活动焦点管理器。
		 */
		function deactivate():void;
		/**
		 *  检索包含指定对象的 IFocusManagerComponent 对象（如果有）。
		 * Flash Player 可以将焦点设置在子组件上，也可以设置在组件本身。 此方法用于查找具有焦点的组件或包含具有焦点的子组件的组件。
		 * 参数
		 * component:InteractiveObject — 可以具有 Flash Player 级别焦点的对象。
		 * 返回
		 * InteractiveObject — 包含指定对象的 IFocusManagerComponent，否则此方法将返回 null。
		 */
		function findFocusManagerComponent(component:InteractiveObject):InteractiveObject;
		/**
		 * 检索接下来将要获得焦点的组件（如果用户使用 Tab 键让焦点移动）。
		 * 如果焦点向前或向后移动一个元素，此方法可以用于检测 Tab 键循环中下一个获得焦点的组件。 如果此应用程序不包含其它有效组件，此方法将检索具有焦点的当前组件。
		 * 参数
		 * backward:Boolean (default = false) — 指示焦点是否通过 Tab 键循环向后移动。如果该值为 true，此方法返回将要具有焦点的组件（如果用户按 Shift+Tab 按键组合让焦点向后移动）。
		 * 返回
		 * InteractiveObject — 接下来将要获得焦点的组件。
		 */
		function getNextFocusManagerComponent(backward:Boolean=false):InteractiveObject;
	}
}

